GUI Functions

Legend:
x is X (left) coordinate, y is Y (top) coordinate, w is Width and h is Height, all of x, y, w and h are v|n.
#v|n is the Object ID and is in the range [1...999]

CHECKBOX(#v|n)

Returns 0 if the given checkbox is unchecked and 1 if it is checked

COLORSELECT(v|n)

Opens the Palm OS standard color selector window, and returns the selected color

Notes:

• v|n is the initial proposed color
• PalmOS 3.5 onwards

DOEVENTS

Returns on which object an event occurred (if one occurred)

Return Value	Comment	KEYEVENTS Required
-24, -23, -22, -21	App Key #4, #3, #2, #1	ON
-13	HotSync Button on Cradle	ON | PARTIAL
-12	Page Down Button	ON | PARTIAL
-11	Page Up Button	ON | PARTIAL
-10	Power On/Off Button	ON | PARTIAL
-1	ExitAppRequest
0	No event
#v|n in [1..999]	Object that was clicked (Button, CheckBox, ListChoice, PopupChoice, PushButton, ScrollBar or TextSelector)
1000	Pen event (get related information from the PENDOWN, PENX and PENY functions)
1001	Menu event (get related information from the MENUITEM function)
1002	ABOUTBOX event (for information back to your program)

Notes:

• You will usually include a DOEVENTS in a DO/LOOP, REPEAT/UNTIL or WHILE/WEND loop and track for the exit of program condition. Example:

  REPEAT
    E=DOEVENTS
    [Statement]
  UNTIL E<0

• Unless you want to monitor hard keys (which are usually devoted to launching programs, you just have to check that DOEVENTS returns a negative value to exit your program if the KEYEVENTS directive is set.

FONTSELECT(v|n)

Opens the Palm OS standard font selector window, and returns the selected font

Notes:

• The v|n parameter is the default highlighted font in the dialog box and it has to be one of these three values:

  0 stdFont
  1 boldFont
  7 largeBoldFont

FONTWIDTH(c|t, v|n)

Returns the width in pixels of the c|t text for a given font v|n

Notes:

• Please refer to the SETFONT statement as for the possible values for v|n

GETFOCUS

Returns the object ID that has the focus

MENUITEM

Returns the last menu item ID which was selected during the last menu event, 0 if the menu was just opened or -1 if the menu was just closed

Notes:

• The returned ID is the one of the menu item as defined in the MBAR resource
• You should capture the menu event with a DOEVENTS or a WAITEVENT and get the selected menu item just afterwards

MESSAGEBOX(c|t1 [+ c|t2 [+ c|t3]], v|n)

Pops up a message window, with a choice of return buttons given by v|n, and returns the button pressed (1=first , 2=second, ...)

Notes:

• You may pass up to 3 text strings to build a MessageBox with up to 186 characters long (including line feeds)
• v|n is the type of MessageBox with the following return buttons:

  0= Done
  1= OK
  2= OK|Cancel
  3= Yes|No
  4= 1|2
  5= 1|2|3
  6= 1|2|3|4
  7= 1|2|3|4|5
  8= 1|2|3|4|5|6
  9= 1|2|3|4|5|6|7

NOTICEBOX(v|n)

Pops up a message window, with a choice of return buttons given by v|n, and returns the button pressed (1=first , 2=second, ...) or 0 if the message resource does not exist.

The message has to be defined at design time, which is the main difference with MESSAGEBOX.

Notes:

• v|n is a custom message ID as provided in a resource file, the resource being of type Talt (Alert resource, please refer to the RESOURCEFILE compiling directive)
• v|n is to be in the range [1...999]
• the differences between MESSAGEBOX and NOTICEBOX are that MESSAGEBOX's text is created on the fly but it comes with predefined button sets, whilst NOTICEBOX takes a predefined message from a resource file but allowing more customized button labels. If you do not know or want to manage a resource file, then consider using MESSAGEBOX

PENDOWN

Returns 1 when pen is down and 0 when pen is up

Notes:

• PENDOWN is trapped during a DOEVENTS or a WAITEVENT call (return value of pen event is 1000)

PENX

Returns X position of where the pen was last ticked on the screen

PENY

Returns Y position of where the pen was last ticked on the screen

Notes:

• PENX/PENY is trapped during a DOEVENTS or a WAITEVENT call (return value of pen event is 1000)

PUSHBUTTON(#v|n)

Returns the status of a push button: 0=not pushed or 1=pushed

SCROLLBAR(#v|n)

Returns the position of the scroll car of a scrollbar, in the [1...100] range

SELECTEDCHOICE

Returns the selected item (0=non selected, 1=first , 2=second, ...) of the last LISTCHOICE or POPUPCHOICE event

Notes:

• You should capture the ListChoice or the PopupChoice event with a DOEVENTS or a WAITEVENT and get the selected item just afterwards

WAITEVENT

Returns the same values as DOEVENTS (except for the 0=no event value)

Notes:

• be aware that control is not returned to your program until one event occurs, use DOEVENTS if you need to get control back between events. In other words,

  A=WAITEVENT

  is equivalent to

  REPEAT : A=DOEVENTS : UNTIL A<>0

DATESELECT$(c|t)

Opens the Palm OS standard date selector window, and returns the selected date

Notes:

• c|t is the default date sent to the Date Selector, format is "DD/MM/YYYY". Pass an empty text string if you wish to send the current date.
• date format returned is "DD/MM/YYYY" or empty if the user cancelled the input

FIELD$(#v|n)

Retrieves the value stored in a NumField or a TextField

Notes:

• to convert the returned value in a NumField to a number, use the VAL function
• see the FIELD$$ function in the MegaString chapter

TIMESELECT$(c|t)

Opens the Palm OS standard time selector window, and returns the selected time

Notes:

• c|t is the default time sent to the Time Selector, format is "HH:mm". Pass an empty text string if you wish to send the current time.
• time format returned is "HH:mm" or empty if the user cancelled the input
• be careful with this time format as it differs from the "HH:mm:ss" format used in the TIME$ function
• PalmOS 3.1 onwards